Camera Initialization

Camera Initialization

This chapter introduces how to call the SDK APIs to realize basic camera control functions such as enumeration, turning on and off the camera. Based on these, subsequent key functions such as parameter configuration, image acquisition, and image processing on your application can be realized.

Basic flows include:

1. Enumerate Camera(s)
2. Create Camera Instance
3. Turn on Camera
4. (Optional) Parameter Configuration
5. Turn off Camera
6. Destroy Camera Instance

Step 1 Enumerate Camera(s)

To control cameras, enumerate cameras through SDK first.

Enumerate Camera(s)

Call one of the following APIs as needed. Enumeration method is the same for different types of cameras.

• Option 1: Call MV_CC_EnumDevices() to get the device list. You need to pass device interfaces nTLayerType. The device list of the corresponding device interfaces will be returned.

  Device interfaces and corresponding enumerated devices available are as follows, and see Device Type .

  Device Interface	Enumerated Devices
  MV_GIGE_DEVICE	All GigE cameras connected to the frame grabber, including virtual GigE cameras and GigE cameras.
  MV_USB_DEVICE	All USB cameras, including virtual USB cameras.
  MV_CAMERALINK_DEVICE	All serial port devices, including Camera Link cameras and serial port light controllers.
  MV_GENTL_CAMERALINK_DEVICE	All Camera Link cameras connected to the Camera Link frame grabbers.
  MV_GENTL_CXP_DEVICE	All CoaXPress cameras connected to the CoaXPress frame grabbers.
  MV_GENTL_XOF_DEVICE	All XoFLink cameras connected to the XoFLink frame grabbers.
  MV_GENTL_VIR_DEVICE	All virtual cameras connected to the virtual frame grabbers.

  Attention

  The memory of device list is internally allocated. When this API is called, SDK will release and apply for the device list memory. It is recommended to avoid multithreaded enumeration operations.
  

  The sample code is as follows:

  deviceList = MV_CC_DEVICE_INFO_LIST()
  tlayerType = (MV_GIGE_DEVICE | MV_USB_DEVICE | MV_GENTL_CAMERALINK_DEVICE | MV_GENTL_CXP_DEVICE | MV_GENTL_XOF_DEVICE)
  
  # Enumerate devices
  ret = MvCamera.MV_CC_EnumDevices(tlayerType, deviceList)
  if ret != 0:
      print ("enum devices fail! ret[0x%x]" % ret)
      sys.exit()

• Option 2: Call MV_CC_EnumDevicesEx() to get the device list. Compared with the general enumeration API MV_CC_EnumDevices(), you can pass the manufacturer name strManufacturerName to get the corresponding enumeration results. The device list of the corresponding manufacturers will be returned.

  The sample code is as follows:

  deviceList = MV_CC_DEVICE_INFO_LIST()
  tlayerType = (MV_GIGE_DEVICE | MV_USB_DEVICE | MV_GENTL_CAMERALINK_DEVICE | MV_GENTL_CXP_DEVICE | MV_GENTL_XOF_DEVICE)
  strManufacturerName = ‘XXX’
  
  # Enumerate devices
  ret = MvCamera.MV_CC_EnumDevicesEx(tlayerType, deviceList, strManufacturerName)
  if ret != 0:
      print ("enum devices fail! ret[0x%x]" % ret)
      sys.exit()

• Option 3: Call MV_CC_EnumDevicesEx2() to get the device list. Compared with the general enumeration API MV_CC_EnumDevices(), for calling this API, you can:

  • Pass the manufacturer name strManufacturerName to get the device list corresponding to manufacturer names. If strManufacturerName is NULL, the device list of all manufacturers will be returned.

  • Sort the devices from the returned device list. Supports multiple sorting methods such as serial No. and device IP address.

  • Enumerate devices according to the enumeration type nTLayerType. If nTLayerType is MV_GIGE_DEVICE, only GigE cameras in the same network segment will be enumerated, excluding the virtual GigE cameras and cameras connected to GigE frame grabbers.

  The sample code is as follows:

  deviceList = MV_CC_DEVICE_INFO_LIST()
  tlayerType = (MV_GIGE_DEVICE | MV_USB_DEVICE | MV_GENTL_CAMERALINK_DEVICE | MV_GENTL_CXP_DEVICE | MV_GENTL_XOF_DEVICE)
  strManufacturerName = ‘XXX’
  
  # Enumerate devices
  ret = MvCamera.MV_CC_EnumDevicesEx2(tlayerType, deviceList, strManufacturerName, SortMethod_SerialNumber)
  if ret != 0:
      print ("enum devices fail! ret[0x%x]" % ret)
      sys.exit()

• Option 4: Enumerate cameras connected to the specified frame grabber.

  If you need to enumerate the cameras connected to the specific frame grabber, you can enumerate the frame grabber first and turn on the specific frame grabber to enumerate cameras. Details are as follows:

  1. Enumerate frame grabbers.
  2. Create frame grabber instance
  3. Turn on the frame grabber.
  4. Call MV_CC_EnumDevicesByInterface() and input frame grabber handle to get cameras connected to the frame grabber.

  Note

  For operations of enumerating devices, creating instance and turning on frame grabbers, refer to the chapter Frame Grabber Initialization.

Optimize Enumeration Time of GigE Devices and Serial Port Devices

You can refer to the following method to optimize enumeration time of GigE devices and serial port devices.

• Enumeration time setting of the GigE cameras

  When enumerating GigE cameras, SDK will traverse all NICs, and receive response while sending enumeration commands to every NIC. If waiting time outs, SDK will enumerate the next NIC. The current timeout is 100 ms. Enumeration time will be longer if there are more NICs. Enumeration time of every NIC can be reduced as needed to reduce overall enumeration time of GigE devices.

  The following sample code shows how to configure timeout duration of GigE cameras, and sort enumerated cameras by serial No.

  # Configure the timeout duration of GigE camera enumeration
  ret = MvCamera.MV_GIGE_SetEnumDevTimeout(50) 
  if ret != 0: 
      print ("MV_GIGE_SetEnumDevTimeout devices fail! ret[0x%x]" % ret) sys.exit()
      sys.exit()
  
  deviceList = MV_CC_DEVICE_INFO_LIST()
  tlayerType = (MV_GIGE_DEVICE | MV_USB_DEVICE | MV_GENTL_CAMERALINK_DEVICE | MV_GENTL_CXP_DEVICE | MV_GENTL_XOF_DEVICE)
  strManufacturerName = ‘XXX’
  
  # Enumerate devices
  ret = MvCamera.MV_CC_EnumDevicesEx2(tlayerType, deviceList, strManufacturerName, SortMethod_SerialNumber)
  if ret != 0:
      print ("enum devices fail! ret[0x%x]" % ret)
      sys.exit()

• Optimize enumeration time of serial port devices

  Serial port devices communicate through the serial port. If the industrial PC provides several serial ports, SDK will traverse all serial ports to search for the needed camera during enumeration. Due to low communication speed of serial port, this process may result in long enumeration time.

  For optimization, you can:

  1. Call MV_CAML_GetSerialPortList() to get all serial port lists of the PC.

  2. Call MV_CAML_SetEnumSerialPorts() to configure specified serial ports needed during enumeration

  3. Call MV_CC_EnumDevices() to enumerate serial port devices.

  The sample code is as follows:

  # Get all serial ports of the PC
  stSerialList = MV_CAML_SERIAL_PORT_LIST()
  ret = MvCamera.MV_CAML_GetSerialPortList(stSerialList)
  if ret != 0:
      print ("MV_CAML_GetSerialPortList devices fail! ret[0x%x]" % ret)
      sys.exit() 
  
  print ("find %d devices!" % stSerialList.nSerialPortNum)
  
  
  # Configure part of enumerated serial ports based on the actual situation
  enumSerialList = MV_CAML_SERIAL_PORT_LIST()
  
  ret = MvCamera.MV_CAML_SetEnumSerialPorts(enumSerialList)
  if ret != 0:
      print ("MV_CAML_SetEnumSerialPorts devices fail! ret[0x%x]" % ret)
      sys.exit()
  
  # Enumerate Camera Link devices
  deviceList = MV_CC_DEVICE_INFO_LIST()
  ret = MvCamera.MV_CC_EnumDevices(MV_GENTL_CAMERALINK_DEVICE, deviceList)
  if ret != 0:
      print ("enum devices fail! ret[0x%x]" % ret)
      sys.exit()

Step 2 Create Camera Instance

Create camera instance via the following method.

Call MV_CC_CreateHandle() to create camera instance. You need to pass device information pstDevInfo. Different camera instances will be created according to device information.

The sample code is as follows:

# Create the camera instance
cam = MvCamera()

# Select a device, and create a handle
stDeviceList = cast(deviceList.pDeviceInfo[int(nConnectionNum)], POINTER(MV_CC_DEVICE_INFO)).contents

ret = cam.MV_CC_CreateHandle(stDeviceList)
if ret != 0:
    print ("create handle fail! ret[0x%x]" % ret)
    sys.exit()

Step 3 Turn on Camera

"Turn on camera" refers to establishing the connection between the camera instance and physical camera, so that the camera instance can gain access permission and establish communication with the physical camera.

• Option 1: Call MV_CC_OpenDevice() to turn on the camera. In this way, the camera instance owns the exclusive permission to the physical camera.

  The sample code is as follows:

  # Turn on the device
  ret = cam.MV_CC_OpenDevice()
  if ret != 0:
      print ("open device fail! ret[0x%x]" % ret)
      sys.exit()

• Option 2: Call MV_CC_OpenDevice() to turn on the GigE camera. You need to pass nAccessMode (access permission) and nSwitchoverKey (secret key for switching access permission).

  Attention

  This API is only applicable to GigE cameras and cameras connected to GEV frame grabbers.
  

  The sample code is as follows:

  # Turn on the device
  ret = cam.MV_CC_OpenDevice(MV_ACCESS_Exclusive, 0)
  if ret != 0:
      print ("open device fail! ret[0x%x]" % ret)
      sys.exit()

(Optional) Step 4 Configure Parameters

After turning on the camera, you can:

• Configure device parameters. For more details, refer to the chapter Parameter Configuration.

• Get normal notification events and exception alarm events. For more details, refer to the chapter Event and Exception.

• Perform image acquisition related features. For more details, refer to the chapter Image Acquisition.

• Perform operations of image processing after image acquisition. For more details, refer to the chapter Image Processing.

Step 5 Turn off Camera

When the communication between camera instance and physical camera is no longer needed, call MV_CC_CloseDevice() to turn off the camera.

The sample code is as follows:

# Turn off the device
ret = cam.MV_CC_CloseDevice()
if ret != 0:
    print ("close deivce fail! ret[0x%x]" % ret)
    sys.exit()

Step 6 Destroy Camera Instance

Call MV_CC_DestroyHandle() to destroy camera instance and release resources occupied by camera instance.

Attention

After this API is called, the previous camera instance will be invalid and cannot be used for other APIs anymore.

The sample code is as follows:

# Destroy the handle
ret = cam.MV_CC_DestroyHandle()
if ret != 0:
    print ("destroy handle fail! ret[0x%x]" % ret)
    sys.exit()

Previous: SDK Initialization

Next: Frame Grabber Initialization